
Lisp Mode Help


                                          help version: 2.0
                                               created: 03/07/00 {01:10:49 am}
                                           last update: 12/01/00 {01:36:04 pm}


This document describes the Lisp mode for the software Alpha.  


	  	Description of files


This package includes four files for the Lisp mode:

    "lispMode.tcl"        (version 2.0)
    "LispCompletions.tcl"
    "Lisp Tutorial.el"

and

	Lisp Mode Help (this file)

It also includes an update for the Scheme mode, 

    "schemeMode.tcl"       (version 2.0)
    "ScmCompletions.tcl"


A Macintosh version of "PowerLisp" can be found at

    <http://www.corman.net/PowerLisp.html>

Other Lisp applications can be found at

    <http://www.lisp.org/>


	  	General Notes About Lisp Mode


(1)  Lisp mode serves primarily primarily to make it easier to read and
     write Lisp files -- it colorizes keywords, and sets some
     indentation, electric, word break, and commenting preferences.
     
	 Lisp mode includes its own menu, which mainly includes Help and
	 navigation items, and can allow Alpha to serve as a front end for a
	 local Lisp application.  This menu is also be used in Scm mode.

(2)  Lisp mode contains a full set of electric completions, as well as a 
     Completions Tutorial via the  "Config --> Mode Prefs"  menu item.

(3)  An example syntax file is available via the "Examples Help" file. 
     If you open an example syntax file through the provided hyperlinks, it
     will open in a "shell" window.  After you close the window, clicking
     on the hyperlink will return the unblemished original.

(4)  Both Lisp and Scm modes allow for user customization of keyword
	 dictionaries via the "Config --> Mode Prefs --> Preferences" dialog. 
	 New keywords and color changes will take effect immediately, without
	 the need for a restart or changing windows.
     
(5)  Instructions for editing a LispPrefs.tcl file are given below.  
     Any keywords added will not only be colorized, but included
     in the completions routines as well.

(6)  Lisp mode has Mark File [M] and Parse Function {} capabilities.

(7)  Finally, on-line help is available for the Lisp mode through 
     command double-clicking.  The URL to which the keywords are sent 
     can be configured the the Mode Preferences dialog.


	======================================================================


	  	Specific Notes About Lisp Mode



	  	 	Keywords


Keyword dictionaries are in "lispMode.tcl", including the lists of:


Accessors
Classes
Condition Types
Constant Variables
Declarations
Functions
Macros
Restarts
Specials
Standard Generic Functions
Symbols 
System Classes 
Types
Type Specifiers
Variables

Keyword dictionaries for Scheme are in "schemeMode.tcl".

Note:  As of Alpha 7.4, only keywords of 20 characters or less can be 
properly colorized.  All keywords will, however, be eligible as completions.

Both Lisp and Scm modes have a sophisticated indentation procedure, based
upon unmatched parantheses, ignoring parans that appear in comments or
which are embedded in double quotes.  Each mode also has a full set of
electric completions.

Example syntax file:  "Lisp Example.el"

Example syntax file:  "Scheme Example.scm"

Completions Tutorial: "Lisp Tutorial.el"


	  	 	Command double-click


On-line help is available for Lisp commands through command-double-clicking. 
The URL to which the keywords are sent can be changed through the Mode
Preferences dialog.  If the current text is a macro defined within the
current window, rather than a Stata keyword, command double-clicking on it
will find its definition.

Any available syntax information is also available by pressing the control 
key while command-double-clicking.  This information will appear in the 
status bar window.  In some cases, this information is too long to be read 
in its entirety.  Pressing the shift key instead of the control key will 
insert this syntax information as commented text into your current window.

NOTE: These control-command and shift-command double-click features have not
been fully implemented.  See the "LispCompletions.tcl" file for additional
information.


	  	 	Carriage Returns


Lisp mode has its own indentation scheme, based upon unbalanced braces, and
uses the Electric Return, Tab and Braces features.  Each time that you
start a new line with the <return> key, the previous non-commented line is
evaluated for unmatched ( and ) -- ignoring any braces that appear within
double quotes or after valid comment characters.

Lines that begin with ) will have their indentation reduced by one level
to match the line with the matching (, as in

	(defun R-mode  (&optional proc-name) 
	    "Major mode for editing R source.  See S-mode for more help."
	    (interactive)
	    (setq S-proc-prefix "R"
		    ;; S-set-style "GNU"
		    S-default-style 'GNU
	    )
	    (S-mode proc-name)
	)

In some cases, as when you are continuing a command, you might want to
over-ride this behavior.  For example, if you type

	defv|

and press the completion key, the command completes to 

	(defvar |)

Typing "cond" and pressing the completion key again turns the line into

	(defvar (cond |))

If you now press <return>, the next line will automatically indent to

	(defvar (cond 
	    |))

with only one level of indentation.  This would be find if this line
actually terminated the command, but you might want to continue the
command.  To over-ride this behavior, which in this case would increase
the level of indentation for the next line to 2, press <shift>-<return>
instead:

	(defvar (cond 
	        |))

Entire commands can also be reformatted (aligning indentation) with
<control>-<command> I.

The "Full Indent" mode preference determines if continued commands are
indented to the full "Indentation Amount" (which can be set in the
"Config --> Electrics" menu), or just half of this value.

To enter a carriage return with no indentation whatsoever, press 
<control>-<return>.


	  	 	File Marking


Lisp file marking searches the current window for all commands that
begin in column 1 of any given row.  The first 35 characters of a
command that begins a new line will be marked.  Section and subsection
headings will be returned as well.


	The File                    The Mark
	________                    ________

    ;;*;; Section Heading        Section Heading
    ;;;*;;; Subsection Heading  * Subsection Heading
    (command arguments etc        (command arguments etc


Function parsing {} will return only the command name, in alphabetical order.


	  	 	Navigation


Lisp mode has command navigation capabilities, available with the key
bindings control-shift N and P. These items are also bound to control-shift
arrow keys, and to 1 and 3 on the keypad when the num-lock is turned off. 
Entire commands can also be highlighted with control-shift S, or
reformatted (aligning indentation) with control-command I.

Control-shift up and down will find the prev/next command.  The right and
left arrow keys not only find prev/next commands, but will also place the
cursor at the top of the window.

Entire commands can also be highlighted with control-shift S.


	  	 	Adding a Lisp Prefs file


To add additional commands or arguments in a "LispPrefs.tcl" file, go to
"Config --> Mode Prefs --> Edit Prefs File", and add these lines:


	set LispUserCommands {
		blah bladdity
	}
	
	set LispUserArguments {
		blah2 bladdity2
	}
	
	Lisp::colorizeLisp


To add additional commands or arguments in a "ScmPrefs.tcl" file, go to
"Config --> Mode Prefs --> Edit Prefs File", and add these lines:


	set ScmUserCommands {
		blah bladdity
	}
	
	set ScmUserArguments {
		blah2 bladdity2
	}
	
	Scm::colorizeScm


Include as many keywords as desired within the braces, separating each
keyword by at least one space or carriage return.  Alpha will automatically
load this preferences file the first that the Lisp/Scm mode is invoked.

Any keywords contained in these categories will not only be colorized, but
will also be included as electric completions.  Don't repeat commands or
arguments that have already been defined.

	  	
	======================================================================


	  	Latest Versions



The latest version of the Lisp mode will be available at

    <http://www.princeton.edu/~cupright/computing/alpha/>

Updated versions will also be posted to Vince's upload site, 

    <ftp://ftp.ucsd.edu/pub/alpha/>

and announced on the ALPHA-D mailing list.  This is a mailing list for
Alpha where you can discuss problems, suggest new features etc.  To
subscribe, email <listserv@listserv.syr.edu> and, in the body of your
message (not the subject line), write:

	SUBSCRIBE ALPHA-D


	  	Future Versions


The Lisp mode was written as a side-project, by someone who doesn't actually 
write Lisp files.  (I was hoping that being able to decipher files in the 
Emacs Speaks Statistics package would help me write the Statistical modes.)

I submit this mode to the Alpha community with the hopes that (i) somebody
else will find it useful, (ii) any errors or updates will be reported to me, 
and (iii) I might inspire somebody to take it even further. I will continue
to maintain it and post updates as necessary, but any contributions are 
certainly welcome.



	  	License and Disclaimer


This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
License for more details.

You should have received a copy of the GNU Library General Public License
along with this library; if not, write to the Free Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA

This mode is free.  Alpha is shareware !   <<register>>


cheers,

-- Craig


Author: Craig Barton Upright
E-mail: <cupright@princeton.edu>
  mail: Princeton University,  Department of Sociology 
        Princeton, New Jersey  08544  USA
   www: <http://www.princeton.edu/~cupright/>

